/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.platformservice.lifecycle.api;

import org.proteusframework.platformservice.IServicePlugin;

import java.lang.reflect.Method;
import java.util.EventListener;
import java.util.EventObject;

/**
 * Provides cross-plugin and cross-platform event notification for service intentions and project activities.
 * <p/>
 * Service Intentions are scoped only to platform service plugins. They are used to represent platform service lifecycle
 * events such as the active UI theme service being replaced by a different UI theme service. For more information, see
 * {@link LifecycleServiceIntentionEvent}.
 * <p/>
 * Activities are scoped to project-centric operations. They are used to represent a lifecycle event that
 * contextually relates to a project, such as a project is about to be saved or has been saved. For
 * more information, see {@link LifecycleActivityEvent}.
 */
public interface ILifecycleService extends IServicePlugin
{
    /**
     * Registers the listener with the lifecycle event notification service.
     *
     * @param listener Non-null lifecycle listener
     */
    <E extends ILifecycleListener> void addLifecycleListener(E listener);

    /**
     * Removes the listener from the lifecycle event notification service.
     *
     * @param listener Lifecycle listener
     */
    <E extends ILifecycleListener> void removeLifecycleListener(E listener);

    /**
     * Lifecycle notification that the source associated in the specific context is declaring an <b>serviceIntention</b>
     * to transition through a specific lifecycle event sequence.
     *
     * @param event Lifecycle service intention event
     */
    void fireLifecycleEvent(LifecycleServiceIntentionEvent event);

    /**
     * Lifecycle notification that the source associated in the specific context is declaring an <b>activity</b>
     * based event, and that the source is in the current <b>phase</b> of the event.
     *
     * @param event Lifecycle activity event
     */
    void fireLifecycleEvent(LifecycleActivityEvent event);

    /**
     * Lifecycle notification that a custom event has been registered with the lifecycle service, and the event is
     * now ready to accept listener subscriptions.
     *
     * @param event Lifecycle custom event registration event
     */
    void fireLifecycleEvent(LifecycleCustomEventRegistration event);

    <T extends EventObject, S extends EventListener> void registerCustomEventType(Class<T> customEventType, Class<S> eventListenerType, Method listenerCallbackMethod);

    void addCustomListener(EventListener listener);

    <T extends EventObject> void addCustomListener(Class<T> customEventType, EventListener listener);

    <T extends EventObject> void fireCustomEvent(Class<T> customEventType, T event);

    <T extends EventObject> void fireCustomEvent(T event);

    <T extends EventObject> void removeCustomListener(Class<T> customEventType, EventListener listener);

    void removeCustomListener(EventListener listener);

    <T extends EventObject> void unregisterCustomEventType(Class<T> customEventType);

    <T extends EventObject> boolean isCustomEventRegistered(Class<T> customEventType);
}
